home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1994 November / macformat-018.iso / Utility Spectacular / Utilities / Calc / help / obj < prev    next >
Encoding:
Text File  |  1992-02-24  |  6.5 KB  |  176 lines  |  [TEXT/????]
  1. Using objects
  2.  
  3.     Objects are user-defined types which are associated with user-
  4.     defined functions to manipulate them.  Object types are defined
  5.     similarly to structures in C, and consist of one or more elements.
  6.     The advantage of an object is that the user-defined routines are
  7.     automatically called by the calculator for various operations,
  8.     such as addition, multiplication, and printing.  Thus they can be
  9.     manipulated by the user as if they were just another kind of number.
  10.  
  11.     An example object type is "surd", which represents numbers of the form
  12.  
  13.         a + b*sqrt(D),
  14.  
  15.     where D is a fixed integer, and 'a' and 'b' are arbitrary rational
  16.     numbers.  Addition, subtraction, multiplication, and division can be
  17.     performed on such numbers, and the result can be put unambiguously
  18.     into the same form.  (Complex numbers are an example of surds, where
  19.     D is -1.)
  20.  
  21.     The "obj" statement defines either an object type or an actual
  22.     variable of that type.  When defining the object type, the names of
  23.     its elements are specified inside of a pair of braces.  To define
  24.     the surd object type, the following could be used:
  25.  
  26.         obj surd {a, b};
  27.  
  28.     Here a and b are the element names for the two components of the
  29.     surd object.
  30.  
  31.     When an object is created, the elements are all defined with null
  32.     values.  A user-defined routine should be provided which will place
  33.     useful values in the elements.  For example, for an object of type
  34.     'surd', a function called 'surd' can be defined to set the two
  35.     components as follows:
  36.     
  37.         define surd(a, b)
  38.         {
  39.             local x;
  40.  
  41.             obj surd x;
  42.             x.a = a;
  43.             x.b = b;
  44.             return x;
  45.         }
  46.  
  47.     When an operation is attempted for an object, user functions with
  48.     particular names are automatically called to perform the operation.
  49.     These names are created by concatenating the object type name and
  50.     the operation name together with an underscore.  For example, when
  51.     multiplying two objects of type surd, the function "surd_mul" is
  52.     called.
  53.  
  54.     The user function is called with the necessary arguments for that
  55.     operation.  For example, for "surd_mul", there are two arguments,
  56.     which are the two numbers.  The order of the arguments is always
  57.     the order of the binary operands.  If only one of the operands to
  58.     a binary operator is an object, then the user function for that
  59.     object type is still called.  If the two operands are of different
  60.     object types, then the user function that is called is the one for
  61.     the first operand.
  62.  
  63.     The above rules mean that for full generality, user functions
  64.     should detect that one of their arguments is not of its own object
  65.     type by using the 'istype' function, and then handle these cases
  66.     specially.  In this way, users can mix normal numbers with object
  67.     types.  (Functions which only have one operand don't have to worry
  68.     about this.)  The following example of "surd_mul" demonstrates how
  69.     to handle regular numbers when used together with surds:
  70.  
  71.         define surd_mul(a, b)
  72.         {
  73.             local x;
  74.  
  75.             obj surd x;
  76.             if (!istype(a, x)) {    
  77.                 /* a not of type surd */
  78.                 x.a = b.a * a;
  79.                 x.b = b.b * a;
  80.             } else if (!istype(b, x)) {
  81.                 /* b not of type surd */
  82.                 x.a = a.a * b;
  83.                 x.b = a.b * b;
  84.             } else {            
  85.                 /* both are surds */
  86.                 x.a = a.a * b.a + D * a.b * b.b;
  87.                 x.b = a.a * b.b + a.b * b.a;
  88.             }
  89.             if (x.b == 0)
  90.                 return x.a;    /* normal number */
  91.             return x;        /* return surd */
  92.         }
  93.  
  94.     In order to print the value of an object nicely, a user defined
  95.     routine can be provided.  For small amounts of output, the print
  96.     routine should not print a newline.  Also, it is most convenient
  97.     if the printed object looks like the call to the creation routine.
  98.     For output to be correctly collected within nested output calls,
  99.     output should only go to stdout.  This means use the 'print'
  100.     statement, the 'printf' function, or the 'fprintf' function with
  101.     'files(1)' as the output file.  For example, for the "surd" object:
  102.  
  103.         define surd_print(a)
  104.         {
  105.             print "surd(" : a.a : "," : a.b : ")" : ;
  106.         }
  107.  
  108.     It is not necessary to provide routines for all possible operations
  109.     for an object, if those operations can be defaulted or do not make
  110.     sense for the object.  The calculator will attempt meaningful
  111.     defaults for many operations if they are not defined.  For example,
  112.     if 'surd_square' is not defined to square a number, then 'surd_mul'
  113.     will be called to perform the squaring.  When a default is not
  114.     possible, then an error will be generated.
  115.  
  116.     Please note: Arguments to object functions are always passed by
  117.     reference (as if an '&' was specified for each variable in the call).
  118.     Therefore, the function should not modify the parameters, but should
  119.     copy them into local variables before modifying them.  This is done
  120.     in order to make object calls quicker in general.
  121.  
  122.     The double-bracket operator can be used to reference the elements
  123.     of any object in a generic manner.  When this is done, index 0
  124.     corresponds to the first element name, index 1 to the second name,
  125.     and so on.  The 'size' function will return the number of elements
  126.     in an object.
  127.  
  128.     The following is a list of the operations possible for objects.
  129.     The 'xx' in each function name is replaced with the actual object
  130.     type name.  This table is displayed by the 'show objfuncs' command.
  131.  
  132.         Name    Args    Comments
  133.  
  134.         xx_print    1    print value, default prints elements
  135.         xx_one      1    multiplicative identity, default is 1
  136.         xx_test     1    logical test (false,true => 0,1), 
  137.                     default tests elements
  138.         xx_add      2    
  139.         xx_sub      2    subtraction, default adds negative
  140.         xx_neg      1    negative
  141.         xx_mul      2    
  142.         xx_div      2    non-integral division, default multiplies 
  143.                     by inverse
  144.         xx_inv      1    multiplicative inverse
  145.         xx_abs      2    absolute value within given error
  146.         xx_norm     1    square of absolute value
  147.         xx_conj     1    conjugate
  148.         xx_pow      2    integer power, default does multiply, 
  149.                     square, inverse
  150.         xx_sgn      1    sign of value (-1, 0, 1)
  151.         xx_cmp      2    equality (equal,non-equal => 0,1), 
  152.                     default tests elements
  153.         xx_rel      2    inequality (less,equal,greater => -1,0,1)
  154.         xx_quo      2    integer quotient
  155.         xx_mod      2    remainder of division
  156.         xx_int      1    integer part
  157.         xx_frac     1    fractional part
  158.         xx_inc      1    increment, default adds 1
  159.         xx_dec      1    decrement, default subtracts 1
  160.         xx_square   1    default multiplies by itself
  161.         xx_scale    2    multiply by power of 2
  162.         xx_shift    2    shift left by n bits (right if negative)
  163.         xx_round    2    round to given number of decimal places
  164.         xx_bround   2    round to given number of binary places
  165.         xx_root     3    root of value within given error
  166.         xx_sqrt     2    square root within given error
  167.  
  168.  
  169.     Also see the library files:
  170.  
  171.         dms.cal
  172.         mod.cal
  173.         poly.cal
  174.         quat.cal
  175.         surd.cal
  176.